home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 2010 April / PCWorld0410.iso / hity wydania / Ubuntu 9.10 PL / karmelkowy-koliberek-desktop-9.10-i386-PL.iso / casper / filesystem.squashfs / usr / share / doc / libcouchdb-glib-1.0-1 / README < prev   
Text File  |  2009-09-01  |  4KB  |  90 lines
  1. CouchDB-glib is a GLib-based implementation of the client side protocol for
  2. CouchDB (http://couchdb.apache.org), a replication and synchronization
  3. database from the Apache project.
  4.  
  5. Building
  6. ========
  7. To build it, the following dependencies are needed:
  8.  
  9.     * json-glib >= 0.7.2
  10.     * glib and gobject
  11.     * libsoup >= 2.4
  12.  
  13. To actually build it, do the following:
  14.  
  15.     ./configure (or ./autogen.sh if there is no configure script)
  16.     make
  17.     make install
  18.  
  19. API
  20. ===
  21. The main entry point in the API is the CouchDB object, which is needed for all
  22. operations involving access to the CouchDB databases. To create it:
  23.  
  24.     couchdb = couchdb_new (hostname);
  25.  
  26. The only argument is to specify the hostname of the CouchDB instance you want
  27. to connect to. If NULL, it will connect to the default, which is
  28. http://localhost:5984.
  29.  
  30. Once you have a valid CouchDB object, you can perform several operations on
  31. databases:
  32.     * List databases -> couchdb_list_databases()
  33.     * Create a database -> couchdb_create_database()
  34.     * Delete a database -> couchdb_delete_database()
  35.     * List documents in a database -> couchdb_list_documents()
  36.  
  37. There is also a polling mechanism, which allows your application to listen
  38. for changes on a specific database on the CouchDB instance you're connecting
  39. to. To start listening for changes, you just need to:
  40.     * Call couchdb_listen_for_changes
  41.     * And g_signal_connect the CouchDB object to the following signals:
  42.         - "database_created"
  43.         - "database_deleted"
  44.         - "document_created"
  45.         - "document_updated"
  46.         - "document_deleted"
  47.  
  48. Documents can easily be managed by using the CouchDBDocument object, which
  49. provides an API for creating new documents in memory and save them on a
  50. database on the CouchDB instance you're connected to:
  51.     * Create an empty, in-memory document -> couchdb_document_new()
  52.     * Get an existing document from the database -> couchdb_document_get()
  53.     * Delete an existing document -> couchdb_document_delete()
  54.  
  55. Documents' API provides meaningful functions to manage its contents. First of
  56. all, there are standard fields on each document, which you can set/get easily:
  57.     * Unique ID -> couchdb_document_get_id() and couchdb_document_set_id()
  58.     * Revision -> couchdb_document_get_revision() and
  59.           couchdb_document_set_revision()
  60.     * Record type -> couchdb_document_get_record_type() and
  61.       couchdb_document_set_record_type()
  62.     * Application annotations (application-specific data) ->
  63.       couchdb_document_get_application_annotations() and
  64.       couchdb_document_set_application_annotations()
  65.  
  66. Apart from those standard fields, documents can have whatever fields you need
  67. to, so the CouchDBDocument API provides functions for setting fields of
  68. different types:
  69.     * Booleans -> couchdb_document_get_boolean_field() and
  70.       couchdb_document_set_boolean_field()
  71.     * Integers -> couchdb_document_get_int_field() and
  72.       couchdb_document_set_int_field()
  73.     * Doubles -> couchdb_document_get_double_field() and
  74.       couchdb_document_set_double_field()
  75.     * Strings -> couchdb_document_get_string_field() and
  76.       couchdb_document_set_string_field()
  77.  
  78. There are some structured field types which are also supported:
  79.     * Structs -> couchdb_document_get_struct_field() and
  80.       couchdb_document_set_struct_field(). These use a special type,
  81.       CouchDBStructField, which in turn provides the same get/set functions
  82.       than the CouchDBDocument functions explained above.
  83.     * Arrays (not yet supported)
  84.  
  85. There are also higher level documents management functions, that internally
  86. deal with specific record types. They are just built on top of the
  87. CouchDBDocument API but provide an easy way to deal with those specific
  88. record types:
  89.     * Contacts -> couchdb_document_contact_*
  90.